home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / gfx / conv / jpegV5Abin.lha / doc / cjpeg.man < prev    next >
Text File  |  1995-01-03  |  12KB  |  331 lines
  1.  
  2.  
  3.  
  4. CJPEG(1)                                                 CJPEG(1)
  5.  
  6.  
  7. NAME
  8.        cjpeg - compress an image file to a JPEG file
  9.  
  10. SYNOPSIS
  11.        cjpeg [ options ] [ filename ]
  12.  
  13.  
  14. DESCRIPTION
  15.        cjpeg  compresses  the  named  image file, or the standard
  16.        input if no file is named, and produces a  JPEG/JFIF  file
  17.        on  the  standard  output.   The currently supported input
  18.        file formats are: PPM (PBMPLUS color format), PGM (PBMPLUS
  19.        gray-scale  format), BMP, GIF, Targa, and RLE (Utah Raster
  20.        Toolkit format).   (RLE  is  supported  only  if  the  URT
  21.        library is available.)
  22.  
  23. OPTIONS
  24.        All   switch   names  may  be  abbreviated;  for  example,
  25.        -grayscale may be written  -gray  or  -gr.   Most  of  the
  26.        "basic"  switches  can  be abbreviated to as little as one
  27.        letter.  Upper and lower case are equivalent (thus -GIF is
  28.        the  same  as  -gif).  British spellings are also accepted
  29.        (e.g., -greyscale), though for brevity these are not  men­
  30.        tioned below.
  31.  
  32.        The basic switches are:
  33.  
  34.        -quality N
  35.               Scale  quantization tables to adjust image quality.
  36.               Quality is 0 (worst) to 100 (best); default is  75.
  37.               (See below for more info.)
  38.  
  39.        -grayscale
  40.               Create  monochrome  JPEG file from color input.  Be
  41.               sure  to  use  this  switch  when   compressing   a
  42.               grayscale  GIF  file,  because  cjpeg  isn't bright
  43.               enough to notice  whether  a  GIF  file  uses  only
  44.               shades of gray.  By saying -grayscale, you'll get a
  45.               smaller JPEG file that takes less time to  process.
  46.  
  47.        -optimize
  48.               Perform  optimization  of  entropy encoding parame­
  49.               ters.  Without this,  default  encoding  parameters
  50.               are  used.  -optimize usually makes the JPEG file a
  51.               little smaller, but cjpeg runs somewhat slower  and
  52.               needs much more memory.  Image quality and speed of
  53.               decompression are unaffected by -optimize.
  54.  
  55.        -targa Input file is Targa format.  Targa files that  con­
  56.               tain an "identification" field will not be automat­
  57.               ically recognized by cjpeg; for such files you must
  58.               specify  -targa  to  make  cjpeg treat the input as
  59.               Targa format.  For most Targa files, you won't need
  60.               this switch.
  61.  
  62.  
  63.  
  64.                           30 August 1994                        1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CJPEG(1)                                                 CJPEG(1)
  71.  
  72.  
  73.        The  -quality  switch  lets  you trade off compressed file
  74.        size against  quality  of  the  reconstructed  image:  the
  75.        higher  the quality setting, the larger the JPEG file, and
  76.        the closer the output image will be to the original input.
  77.        Normally  you  want  to  use  the  lowest  quality setting
  78.        (smallest file) that decompresses into something  visually
  79.        indistinguishable  from the original image.  For this pur­
  80.        pose the quality setting should be between 50 and 95;  the
  81.        default of 75 is often about right.  If you see defects at
  82.        -quality 75, then go up 5 or 10 counts at a time until you
  83.        are  happy  with  the  output image.  (The optimal setting
  84.        will vary from one image to another.)
  85.  
  86.        -quality 100 will generate a  quantization  table  of  all
  87.        1's,  eliminating loss in the quantization step (but there
  88.        is still information  loss  in  subsampling,  as  well  as
  89.        roundoff  error).   This setting is mainly of interest for
  90.        experimental purposes.  Quality values above about 95  are
  91.        not  recommended  for normal use; the compressed file size
  92.        goes up dramatically for hardly any gain in  output  image
  93.        quality.
  94.  
  95.        In  the other direction, quality values below 50 will pro­
  96.        duce very small files  of  low  image  quality.   Settings
  97.        around  5 to 10 might be useful in preparing an index of a
  98.        large image library, for example.  Try -quality 2 (or  so)
  99.        for  some  amusing  Cubist effects.  (Note: quality values
  100.        below about 25 generate 2-byte quantization tables,  which
  101.        are considered optional in the JPEG standard.  cjpeg emits
  102.        a warning message when you  give  such  a  quality  value,
  103.        because  some  commercial  JPEG  programs may be unable to
  104.        decode the resulting file.  Use -baseline if you  need  to
  105.        ensure compatibility at low quality values.)
  106.  
  107.        Switches for advanced users:
  108.  
  109.        -dct int
  110.               Use integer DCT method (default).
  111.  
  112.        -dct fast
  113.               Use fast integer DCT (less accurate).
  114.  
  115.        -dct float
  116.               Use  floating-point DCT method.  The floating-point
  117.               method is the most accurate, but will be the  slow­
  118.               est  unless  your  machine  has very fast floating-
  119.               point hardware.  Also  note  that  results  of  the
  120.               floating-point  method  may  vary  slightly  across
  121.               machines, while the integer methods should give the
  122.               same  results  everywhere.  The fast integer method
  123.               is much less accurate than the other two.
  124.  
  125.        -restart N
  126.               Emit a JPEG restart marker every  N  MCU  rows,  or
  127.  
  128.  
  129.  
  130.                           30 August 1994                        2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CJPEG(1)                                                 CJPEG(1)
  137.  
  138.  
  139.               every  N  MCU blocks if "B" is attached to the num­
  140.               ber.  -restart 0 (the  default)  means  no  restart
  141.               markers.
  142.  
  143.        -smooth N
  144.               Smooth  the  input  image  to  eliminate  dithering
  145.               noise.  N, ranging from 1  to  100,  indicates  the
  146.               strength  of  smoothing.   0 (the default) means no
  147.               smoothing.
  148.  
  149.        -maxmemory N
  150.               Set limit for amount of memory to use in processing
  151.               large  images.   Value is in thousands of bytes, or
  152.               millions of bytes if "M" is attached to the number.
  153.               For  example,  -max  4m  selects 4000000 bytes.  If
  154.               more space is needed, temporary files will be used.
  155.  
  156.        -outfile name
  157.               Send  output  image to the named file, not to stan­
  158.               dard output.
  159.  
  160.        -verbose
  161.               Enable debug printout.  More -v's give more output.
  162.               Also, version information is printed at startup.
  163.  
  164.        -debug Same as -verbose.
  165.  
  166.        The  -restart  option  inserts  extra markers that allow a
  167.        JPEG decoder to resynchronize after a transmission  error.
  168.        Without  restart  markers, any damage to a compressed file
  169.        will usually ruin the image from the point of the error to
  170.        the  end of the image; with restart markers, the damage is
  171.        usually confined to the portion of the  image  up  to  the
  172.        next  restart  marker.   Of  course,  the  restart markers
  173.        occupy extra space.  We recommend -restart  1  for  images
  174.        that  will  be transmitted across unreliable networks such
  175.        as Usenet.
  176.  
  177.        The -smooth option filters the input  to  eliminate  fine-
  178.        scale  noise.   This  is  often useful when converting GIF
  179.        files to JPEG: a moderate smoothing factor  of  10  to  50
  180.        gets  rid of dithering patterns in the input file, result­
  181.        ing in a smaller JPEG file  and  a  better-looking  image.
  182.        Too  large a smoothing factor will visibly blur the image,
  183.        however.
  184.  
  185.        Switches for wizards:
  186.  
  187.        -arithmetic
  188.               Use arithmetic coding rather than  Huffman  coding.
  189.               (Not currently supported for legal reasons.)
  190.  
  191.        -baseline
  192.               Force  a  baseline JPEG file to be generated.  This
  193.  
  194.  
  195.  
  196.                           30 August 1994                        3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CJPEG(1)                                                 CJPEG(1)
  203.  
  204.  
  205.               clamps quantization values to 8 bits  even  at  low
  206.               quality settings.
  207.  
  208.        -nointerleave
  209.               Generate  noninterleaved  JPEG  file  (not yet sup­
  210.               ported).
  211.  
  212.        -qtables file
  213.               Use the quantization tables given in the  specified
  214.               file.   The  file should contain one to four tables
  215.               (64 values each) as plain text.  Comments  preceded
  216.               by '#' may be included in the file.  The tables are
  217.               implicitly numbered 0,1,etc.  If -quality N is also
  218.               specified,  the  values  in  the  file  are  scaled
  219.               according to cjpeg's quality scaling curve.
  220.  
  221.        -qslots N[,...]
  222.               Select which quantization table  to  use  for  each
  223.               color  component.   By default, table 0 is used for
  224.               luminance and table 1 for chrominance components.
  225.  
  226.        -sample HxV[,...]
  227.               Set JPEG sampling factors.  If  you  specify  fewer
  228.               H/V  pairs than there are components, the remaining
  229.               components are set to 1x1  sampling.   The  default
  230.               setting is equivalent to -sample 2x2.
  231.  
  232.        The  "wizard"  switches  are  intended for experimentation
  233.        with JPEG.  If you don't know what you  are  doing,  don't
  234.        use  them.   You can easily produce files with worse image
  235.        quality and/or poorer compression than you'll get from the
  236.        default  settings.  Furthermore, these switches should not
  237.        be used  when  making  files  intended  for  general  use,
  238.        because  not all JPEG implementations will support unusual
  239.        JPEG parameter settings.
  240.  
  241. EXAMPLES
  242.        This example compresses the PPM file foo.ppm with a  qual­
  243.        ity factor of 60 and saves the output as foo.jpg:
  244.  
  245.               cjpeg -quality 60 foo.ppm > foo.jpg
  246.  
  247. HINTS
  248.        Color  GIF files are not the ideal input for JPEG; JPEG is
  249.        really  intended  for  compressing   full-color   (24-bit)
  250.        images.   In  particular,  don't  try to convert cartoons,
  251.        line drawings, and other images that have only a few  dis­
  252.        tinct  colors.   GIF  works great on these, JPEG does not.
  253.        If you want to convert a GIF to JPEG, you  should  experi­
  254.        ment  with  cjpeg's  -quality and -smooth options to get a
  255.        satisfactory conversion.  -smooth 10 or so is often  help­
  256.        ful.
  257.  
  258.        Avoid   running   an   image  through  a  series  of  JPEG
  259.  
  260.  
  261.  
  262.                           30 August 1994                        4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CJPEG(1)                                                 CJPEG(1)
  269.  
  270.  
  271.        compression/decompression cycles.  Image quality loss will
  272.        accumulate;  after  ten  or  so  cycles  the  image may be
  273.        noticeably worse than it was after one cycle.   It's  best
  274.        to use a lossless format while manipulating an image, then
  275.        convert to JPEG format when you  are  ready  to  file  the
  276.        image away.
  277.  
  278.        The  -optimize option to cjpeg is worth using when you are
  279.        making a "final" version for posting or  archiving.   It's
  280.        also a win when you are using low quality settings to make
  281.        very small JPEG files; the percentage improvement is often
  282.        a lot more than it is on larger files.
  283.  
  284. ENVIRONMENT
  285.        JPEGMEM
  286.               If  this  environment variable is set, its value is
  287.               the default memory limit.  The value  is  specified
  288.               as  described  for  the -maxmemory switch.  JPEGMEM
  289.               overrides the default value specified when the pro­
  290.               gram  was  compiled, and itself is overridden by an
  291.               explicit -maxmemory.
  292.  
  293. SEE ALSO
  294.        djpeg(1), rdjpgcom(1), wrjpgcom(1)
  295.        ppm(5), pgm(5)
  296.        Wallace, Gregory K.  "The JPEG Still  Picture  Compression
  297.        Standard", Communications of the ACM, April 1991 (vol. 34,
  298.        no. 4), pp. 30-44.
  299.  
  300. AUTHOR
  301.        Independent JPEG Group
  302.  
  303. BUGS
  304.        Arithmetic coding is not supported for legal reasons.
  305.  
  306.        Not all variants of BMP and Targa file  formats  are  sup­
  307.        ported.
  308.  
  309.        The -targa switch is not a bug, it's a feature.  (It would
  310.        be a bug if the Targa format designers had not been  clue­
  311.        less.)
  312.  
  313.        Still not as fast as we'd like.
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                           30 August 1994                        5
  329.  
  330.  
  331.